NUI SDK提供更小的工具包和更完善的状态管理。为满足不同用户需求，NUI SDK既能提供全链路的语音能力，同时可做原子能力SDK进行使用，并保持接口的统一。

输入格式：PCM编码、16bit采样位数、单声道（mono）。

音频采样率：8000Hz/16000Hz。

设置返回结果：是否返回中间识别结果、在后处理中添加标点、将中文数字转为阿拉伯数字输出。

设置多语言识别：在管控台编辑项目中进行模型选择，详情请参见模型选择。

访问类型

说明

URL

外网访问（默认上海地域）

所有服务器均可使用外网访问URL（SDK中默认设置了外网访问URL）。

上海：wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1

北京：wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1

深圳：wss://nls-gateway-cn-shenzhen.aliyuncs.com/ws/v1

ECS内网访问

使用阿里云上海、北京、深圳ECS（即ECS地域为华东2（上海）、华北2（北京）、华南1（深圳）），可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel，即不能在内网访问语音服务；如果希望使用AnyTunnel，需要创建专有网络在其内部访问。

使用内网访问方式，将不产生ECS实例的公网流量费用。

关于ECS的网络类型请参见网络类型。

上海：ws://nls-gateway-cn-shanghai-internal.aliyuncs.com:80/ws/v1

北京：ws://nls-gateway-cn-beijing-internal.aliyuncs.com:80/ws/v1

深圳：ws://nls-gateway-cn-shenzhen-internal.aliyuncs.com:80/ws/v1

服务端的响应除了音频流之外，都会在返回信息的header包含本次识别任务的task_id参数，是本次请求的唯一标识。

客户端在与服务端建立WebSocket连接时，使用Token进行鉴权。关于Token获取请参见获取Token概述。

初始化参数如下。

参数

类型

是否必选

说明

workspace

String

是

工作目录路径，SDK从该路径读取配置文件。

app_key

String

是

管控台创建项目的Appkey。

token

String

是

请确保该Token可以使用并在有效期内。

Token可以在初始化时设置，也可通过参数设置进行更新。

device_id

String

是

设备标识，唯一表示一台设备（如Mac地址/SN/UniquePsuedoID）。

debug_path

String

否

debug目录。当初始化SDK时的save_log参数取值为true时，该目录用于保存中间音频文件。

save_wav

String

否

当初始化SDK时的save_log参数取值为true时，该参数生效。表示是否保存音频debug，该数据保存在debug目录中，需要确保debug_path有效可写。

客户端发起实时语音识别请求前需要进行参数设置，各参数由SDK中setParams接口以JSON格式设置，该参数设置一次即可。各参数含义如下。

参数

类型

是否必选

说明

appkey

String

否

管控台创建的项目Appkey，一般在初始化时设置。

token

String

否

如果需要更新，则进行设置。

service_type

Int

是

需要请求的语音服务类型，实时语音识别为“4”。

direct_ip

String

否

支持客户端自行DNS解析后传入IP进行访问。

nls_config

JsonObject

否

访问语音服务相关的参数配置，详情请参见下表。

参数nls_config配置如下。

参数

类型

是否必选

说明

sr_format

String

否

音频编码格式，支持OPUS编码和PCM原始音频。默认值：OPUS。

如果使用8000Hz采样率，则只支持PCM格式。

sample_rate

Integer

否

音频采样率，默认值：16000Hz。根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。

enable_intermediate_result

Boolean

否

是否返回中间识别结果，默认值：false。

enable_punctuation_prediction

Boolean

否

是否在后处理中添加标点，默认值：false。

enable_inverse_text_normalization

Boolean

否

ITN（逆文本inverse text normalization）中文数字转换阿拉伯数字。设置为True时，中文数字将转为阿拉伯数字输出，默认值：False。

customization_id

String

否

自学习模型ID。

vocabulary_id

String

否

定制泛热词ID。

max_sentence_silence

Integer

否

语音断句检测阈值，静音时长超过该阈值被认为断句。取值范围：200ms～2000ms，默认值：800ms。

enable_words

Boolean

否

是否开启返回词信息。默认值：false。

enable_ignore_sentence_timeout

Boolean

否

是否忽略实时识别中的单句识别超时。默认值：false。

disfluency

Boolean

否

过滤语气词，即声音顺滑，默认值false（关闭），开启时需要设置version为4.0。

vad_model

String

否

设置服务端的vad模型id，默认无需设置。

speech_noise_threshold

float

否

噪音参数阈值，取值范围：-1～+1。

取值越接近-1，判定为语音的概率越大，亦即有可能更多噪声被当作语音被误识别。

取值越接近+1，判定为噪音的越多，亦即有可能更多语音被当作噪音被拒绝掉。

该参数属高级参数，调整需谨慎并进行重点测试。

客户端循环发送语音数据，持续接收识别结果：

EVENT_SENTENCE_START事件表示服务端检测到了一句话的开始。实时语音识别服务的智能断句功能会判断出一句话的开始与结束，如：

header对象参数说明：

参数

类型

说明

namespace

String

消息所属的命名空间。

name

String

消息名称。SentenceBegin表示一个句子的开始。

status

Integer

状态码。表示请求是否成功，参见错误码。

message_id

String

本次消息的ID，由SDK自动生成。

task_id

String

任务全局唯一ID，请记录该值，便于排查问题。

status_text

String

状态消息。

payload对象参数说明：

参数

类型

说明

index

Integer

句子编号，从1开始递增。

time

Integer

当前已处理的音频时长，单位：毫秒。

若enable_intermediate_result设置为true，SDK会持续多次通过onNuiEventCallback回调上报EVENT_ASR_PARTIAL_RESULT事件，即中间识别结果，如：

header对象中name参数取值为TranscriptionResultChanged表示句子的中间识别结果。其余参数说明参见上述表格。

payload对象参数说明：

参数

类型

说明

index

Integer

句子编号，从1开始递增。

time

Integer

当前已处理的音频时长，单位：毫秒。

result

String

当前句子的识别结果。

words

List

当前句子的词信息，需要将enable_words设置为true。

confidence

Double

当前句子识别结果的置信度，取值范围0.0～1.0，值越大表示置信度越高。

EVENT_SENTENCE_END事件表示服务端检测到了一句话的结束，并返回该句话的识别结果，如：

header对象中name参数取值为SentenceEnd表示句子识别结束。其余参数说明参见上述表格。

payload对象参数说明：

参数

类型

说明

index

Integer

句子编号，从1开始递增。

time

Integer

当前已处理的音频时长，单位：毫秒。

begin_time

Integer

当前句子对应的SentenceBegin事件的时间，单位：毫秒。

result

String

当前句子的识别结果。

words

List

当前句子的词信息，需要将enable_words设置为true。

confidence

Double

当前句子识别结果的置信度，取值范围0.0～1.0，值越大表示置信度越高。

其中，Word对象：

参数

类型

说明

text

String

文本。

startTime

Integer

词开始时间，单位：毫秒。

endTime

Integer

词结束时间，单位：毫秒。

客户端通知服务端语音数据发送完毕，服务端识别结束后通知客户端识别完毕。

状态码

状态消息

原因

解决方案

40000000

默认的客户端错误码，对应了多个错误消息。

用户使用了不合理的参数或者调用逻辑。

请参考官网文档示例代码进行对比测试验证。

40000001

The token 'xxx' has expired；

The token 'xxx' is invalid

用户使用了不合理的参数或者调用逻辑。通用客户端错误码，通常是涉及Token相关的不正确使用，例如Token过期或者非法。

请参考官网文档示例代码进行对比测试验证。

40000002

Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!

无效或者错误的报文消息。

请参考官网文档示例代码进行对比测试验证。

40000003

PARAMETER_INVALID;

Failed to decode url params

用户传递的参数有误，一般常见于RESTful接口调用。

请参考官网文档示例代码进行对比测试验证。

40000005

Gateway:TOO_MANY_REQUESTS:Too many requests!

并发请求过多。

如果是试用版调用，建议您升级为商用版本以增大并发。

如果已是商用版，可购买并发资源包，扩充您的并发额度。

40000009

Invalid wav header!

错误的消息头。

如果您发送的是WAV语音文件，且设置format为wav，请注意检查该语音文件的WAV头是否正确，否则可能会被服务端拒绝。

40000009

Too large wav header!

传输的语音WAV头不合法。

建议使用PCM、OPUS等格式发送音频流，如果是WAV，建议关注语音文件的WAV头信息是否为正确的数据长度大小。

40000010

Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!

试用期已结束，并且未开通商用版、或账号欠费。

请登录控制台确认服务开通状态以及账户余额。

40010001

Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal

不支持的接口或参数。

请检查调用时传递的参数内容是否和官网文档要求的一致，并结合错误信息对比排查，设置为正确的参数。

比如您是否通过curl命令执行RESTful接口请求， 拼接的URL是否合法。

40010003

Gateway:DIRECTIVE_INVALID:[xxx]

客户端侧通用错误码。

表示客户端传递了不正确的参数或指令，在不同的接口上有对应的详细报错信息，请参考对应文档进行正确设置。

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

在请求处理完成前客户端主动结束。

无，或者请在服务端响应完成后再关闭链接。

40010005

Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!

客户端发送了当前不支持的消息指令。

请参考官网文档示例代码进行对比测试验证。

40020105

Meta:APPKEY_NOT_EXIST:Appkey not exist!

使用了不存在的Appkey。

请确认是否使用了不存在的Appkey，Appkey可以通过登录控制台后查看项目配置。

40020106

Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!

调用时传递的Appkey和Token并非同一个账号UID所创建，导致不匹配。

请检查是否存在两个账号混用的情况，避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。

403

Forbidden

使用的Token无效，例如Token不存在或者已过期。

请设置正确的Token。Token存在有效期限制，请及时在过期前获取新的Token。

41000003

MetaInfo doesn't have end point info

无法获取该Appkey的路由信息。

请检查是否存在两个账号混用的情况，避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。

41010101

UNSUPPORTED_SAMPLE_RATE

不支持的采样率格式。

当前实时语音识别只支持8000 Hz和16000 Hz两种采样率格式的音频。

41040201

Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!

获取客户端发送的数据超时失败。

客户端在调用实时语音识别时请保持实时速率发送，发送完成后及时关闭链接。

50000000

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常，通常为偶发出现。

一般重试调用即可恢复。

50000001

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常，通常为偶发出现。

一般重试调用即可恢复。

52010001

GRPC_ERROR:Grpc error!

受机器负载、网络等因素导致的异常，通常为偶发出现。

一般重试调用即可恢复。

状态码

状态消息

原因

解决方案

40000004

Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time

请求建立链接后，长时间没有发送任何数据，超过10s后，服务端会返回此错误信息。

请在建立链接后和服务端保持交互，比如持续发送语音流，您可以在采集音频的同时进行发送， 发送结束后及时关闭链接。

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

在请求处理完成前客户端主动结束。

无，或者请在服务端响应完成后再关闭链接。

40270003

DECODE_ERROR

音频解码失败。

请根据实际音频格式，设置对应的format参数。

41000002

APPKEY_KEY_IS_NULL

没有正确设置appkey。

请参考官网文档及示例代码。

配置或参数错误

状态码

状态消息

原因

解决方案

240999

DEFAULT_ERROR

内部默认错误。

内部未明确错误。

240001

NUI_CONFIG_INVALID

配置文件错误。

配置文件错误，请确认传入的资源路径内是否有资源文件。如果是Android平台，请参考代码样例主动使用copyAssets接口。

240002

ILLEGAL_PARAM

非法参数。

请确认传入的格式是否正确，包括字段类型、值范围限制。

240003

ILLEGAL_INIT_PARAM

初始化参数非法。

请确认初始化参数格式是否错误或缺少必须字段。

240004

NECESSARY_PARAM_LACK

缺少必须参数。

请确认接口调用时的必须参数。

240005

NULL_PARAM_ERROR

参数为空。

确认参数是否为空。

240006

NULL_LISTENER_ERROR

未定义事件回调。

确认回调事件是否正确赋值。

240007

NULL_DIALOG_ERROR

无有效对话实例，一般在内部状态错误时发生。

请确认接口调用前是否为正确状态，可使用cancel接口恢复idle状态。

240008

NULL_ENGINE_ERROR

无有效引擎实例，请检查是否初始化成功。

请确认是否初始化成功。

240009

ILLEGAL_DATA

传入音频数据地址或长度非法。

请确认传入的数据长度值。

SDK状态错误

状态码

状态消息

原因

解决方案

240010

ILLEGAL_REENTRANT

退出后调用SDK接口。

不影响功能时可忽略。

240011

SDK_NOT_INIT

SDK未正确初始化。

确认初始化返回值正确再进行其他接口使用。

240012

SDK_ALREADY_INIT

重复调用SDK初始化接口。

确认初始化调用逻辑。

240013

DIALOG_INVALID_STATE

内部对话状态错误。

请阅读SDK流程图，确认是否在错误状态下调用接口。

240014

STATE_INVALID

SDK内部状态错误。

请阅读SDK流程图，确认是否在错误状态下调用接口。

240015

ILLEGAL_FUNC_CALL

该模式无法调用接口。

请确认接口调用是否合理。

系统调用错误

状态码

状态消息

原因

解决方案

240020

MEM_ALLOC_ERROR

内存分配错误。

检查内存是否不足。

240021

FILE_ACCESS_FAIL

文件访问错误。

检查文件是否提供读写权限。

240022

CREATE_DIR_ERROR

创建目录错误。

检查是否有写权限。

SDK内部调用错误

状态码

状态消息

原因

解决方案

240030

CREATE_NUI_ERROR

引擎创建失败。

创建实例失败，一般为系统资源不足。

240031

TEXT_DIALOG_START_FAIL

发起文本理解失败。

文本转语义理解失败，检查网络连接或URL以及Token等信息是否有效。

240032

TEXT_CANCEL_START_FAIL

取消文本理解失败。

可忽略。

240033

WUW_DUPLICATE

动态唤醒词重复。

可忽略。

本地引擎调用错误

状态码

状态消息

原因

解决方案

240040

CEI_INIT_FAIL

本地引擎初始化失败。

请确认本地引擎的模型是否有效、目录是否可读写。

音频错误

状态码

状态消息

原因

解决方案

240051

UPDATE_AUDIO_ERROR

推送音频错误，一般为输入音频长度大于所需音频。

确认推送的音频长度是否非法。

240052

MIC_ERROR

连续2s未获取到音频。

请确认在音频数据回调中是否正确提供所需长度的音频。

网络错误

状态码

状态消息

原因

解决方案

240060

CREATE_DA_REQUEST_ERROR

创建对话助手实例失败

可忽略。

240061

START_DA_REQUEST_ERROR

发起对话助手请求失败

可忽略。

240062

DEFAULT_NLS_ERROR

服务端发生错误。

该错误同时包含服务端返回错误内容。

请参考服务端错误码进一步定位。

240063

SSL_ERROR

创建SSL实例错误。

偶现请忽略。

240064

SSL_CONNECT_FAILED

SSL连接失败。

连接异常，请检查服务URL或者本地网络连接是否正常。

240065

HTTP_CONNECT_FAILED

HTTP连接失败。

服务连接错误，可通过日志文件查看HTTP返回值确认原因。

240066

DNS_FAILED

DNS解析失败。

请检查本地网络是否正常、DNS服务是否正常。

240067

CONNECT_FAILED

Socket连接失败。

检查网络连接。

240068

SERVER_NOT_ACCESS

服务端无法访问。

请检查Token是否过期或者URL是否正确。

240069

SOCKET_CLOSED

Socket已关闭。

偶现请忽略。

240070

AUTH_FAILED

鉴权失败。

请检查是否提供正确的ak_secret，ak_id，app_key，sdk_code和device_id等信息，以及确认是否开通足够配额。

240071

HTTPDNS_FAILED

使用客户端传入的IP连接失败。

如果使用直接传入IP进行访问，请确认IP是否可访问。

240072

HTTP_SEND_FAILED

文件转写HTTP发送失败。

确认网络连接是否正常。

240073

HTTP_RECEIVE_FAILED

文件转写HTTP接收失败。

确认网络连接是否正常。

240074

HTTP_RESPONSE_ERROR

文件转写接收内容解析失败

服务端返回内容错误。

240075

HTTP_SERVER_ERROR

文件转写服务错误。

请参考服务端错误码进一步定位。